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TIME!: A Threefold Digital 
Timer for Windows 



the Windows interface deliv- 
ers bonuses to both users and 
programmers. Users benefit 
because every control within 
an application works in a 
friendly and familiar way — ra- 
dio buttons, check boxes, and 
Ust boxes, to name a few. The 
ease of use and time savings come about 
with relatively little development invest- 
ment, too. Programmers no longer need 
to wrestle with gruesome implementa- 
tion details to create a slick, serviceable 
ntertace. thanks to these Windows con- 
trols supplied by Microsoft. Disparate ap- 
plications also gain a conunon look be- 
cause developers find these standard 
tools so much easier to employ than roll- 
your-own code. Again, end users reap the 
rewards. 

Windows promotes standardization, 
but allows for some extension by provid- 
ing programmers with the means to cre- 
ate custom controls specifically designed 
for an appUcation. TIME!, this issue's 
utility, demonstrates the use of these con- 
trols, while simultaneously deUvering a 
useful program. 

You can download TIMEI.EXE and 
the source code from Library 2 (PCMag 
Utils) of the Utilities/Tips Forum on PC 
MagNct archived as TIMEI.ZIP. If you 
just want the files you need to run TIME!, 
download the self-extracting archive 
TIME.EXE. For instructions, refer to the 
sidebar "Utihties by Modem." If you 
don't have a modem, you can obtain the 
files directly from PC Magazine by send- 
ing a postcard with your name, address, 
and preferred disk size to the attention 
of Katharine West, PC Magazine, One 
Park Ave., New Ycark, NY 10016. Or you 
can fax your request to 212-50S<5799 (no 
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phone calls please). Compiling TIME! re- 
quires Borland C++ 3.0, or Microsoft C 
6.0 and the Windows 'i.x SDK (Software 
Development Kit). 

USING TIME! TIME! works the way the 
cooking timer in your kitchen does. The 
program actually contains three inde- 
pendent timers, each with the ability to 
be set, started, and stopped. All share a 
single display, however, so only one 
timer's setting can appear during any 
given period; the three buttons immedi- 

TIME!y this issue's 
utility y is a triple digital 
timer that shows 



programmers how 
to implement custom 
controls in Windows. 



ately below the display let you make your 
selection. Pressing the Timer 1 button, 
for example, instructs the program to 
show time remaining on its first timer. A 
black bar above the button indicates the 
timer you've chosen. 

The three timers can run simultane- 
ously. The digital display shows the time 
remaining until the currently selected 
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timer reaches zero. Figure 1 shows the 
TIME! window. 

The Minute and Second buttons allow 
you to set the time. To add a minute to 
the currently displayed timer, you simply 
press the Minute button. The Second but- 
ton works the same way. The buttons 
function only if the timer is stopped. 

The Start/Stop button performs its 
functions on the displayed timer only. If 
the timer is running, the button is labeled 
Stop; otherwise it says Start. A timer can 
be started and stopped repeatedly. When 
restarted, the count continues from the 
currently displayed time. For example, if 
you halt a timer that is showing 0:59, add 
one minute, and reactivate it, counting 
continues from the new time — 1:59. 

A shortcut allows you to quickly set 
the displayed time with a minimum of ef- 
fort. Clicking the left mouse button on 
a digit' increases it by one. Clicking the 
right button decreases it a unit. Again, 
the timer must be stopped. 

After you've set and started one or 
more timers, you can minimize the 
TIME! window. When one of the timers 
expires. TIME! pops to the foreground 
and beeps the speaker. 

The look of the TIME! digits can be 
set to resemble either a hquid crystal dis- 
play (LCD) or a Ught-emitting diode 
(LED) display. In LCD mode, TIME! 
displays the digits as black numbers on 
a gray background (like LCD watches). 
LED mode produces red numbers on a 
black background. While LED watches 
went out of style with Disco, red on black 
still looks pretty good. 

Changing the look is simple. Choose 
either LED or LCD from the Display 
menu. Finally, to terminate the program, 
choose Exit. 

To install TIME!, copy the files 
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5e PC Magazine utilities are avail- 
able by modem from PC MagNet, a 
ZiffNet service hosted by Compu- 
Serve. 

To find the phone number nearest 
you, set your communications soft- • 
ware to 300, 1,200, 2.400. or 9,600 bits 
per second. 7 data bits, even parity. 1 
stop bit, and full duplex, then dial 800- 
346-3247 with your modem. When the 
modem connects, press Enter. At the 
HOST NAME prompt, enter 
PHONES. Follow the menus and note 
the number closest to you. Or you can 
call 800-635-6225 (voice) and follow 
the instructions and note the number. 

To obtain the current issue's utihty 
free of charge, simply dial the local 
number; at the HOST NAME 
prompt, type CIS; and at the USER 
ID prompt, enter 601 16,1. Then, at the 
PASSWORD prompt, enter PC- 
MAGUTIL. 

To join ZiffNet, at the USER ID 
prompt, type 177000,5000. Then, at 
the PASSWORD prompt, enter PC* 
MAGNET. Finally, at the ENTER 
AGREEMENT NUMBER 
typePCMAG92. 



Register your name and enter your 
American Express, MasterCard, or 
Visa number. (If you'd like to have 
your company billed instead, call 
CompuServe at 800-848-8990.) Your 
personal user ID and a temporary 
password will be displayed. A new 
password will arrive in the mail within, 
10 days to confirm your subscription. 

ZiffNet membership costs $2.50 
per month. This includes access to PC 
Magazine Editors' Choice Awards, 
Product Reviews index. Weekly News 
from PC Week, Buyers' Market, Ziff- 
Net Highlights, and the Support Fo- 
rum (which also includes the current 
utihty). CompuServe members can 
join by entering GO PCMAG at any 
CompuServe ! prompt. 

Outside of these areas, PC MagNet 
costs $6.30 per hour for 300-bps ser- 
vice. $12.80 for 1 .200 or 2,400 bps, and 
$22.80 for 9,600 bps. Bilhng is based 
on 1 -minute increments. 

These programs can be copied but 
are copyrighted. You may make cop- 
ies for others as long as no charge is 
olved. but making copies for any 
ercial purpose is prohibited. □ 



TIME1.EXE and DIGIT.DLL into a di- 
rectory located on your path. As with all 

Windows programs, TIME! can be run 
from the Program Manager using the 
File; Run menu selection. To make run- 
ning the program convenient, you can in- 
stall the TIME ! icon in the Program Man- 
ager using the File New menu selection. 

WHAT MAKES IT TICK? TIME! is a sim- 
ple Windows appMcation constructed (as 
are many Windows programs) with a 
non-modal dialog box as its main win- 
dow. This eliminates the need to use the 
Windows API to create the controls 
TIME! needs. The size and position of 
the controls are specified by the dialog- 
box template in the program's resource 
script shown in Figure 2. The resource 
compiler is used to compile the script file. 
The resulting file. TIME!. RES, must 
then be bound into the TIME!. EXE file. 

While Windows supplies the standard 
button controls used by TIME!, it pro- 
vides nothing that can show a number in 
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the form of an LCD or LED digit. These 
are displayed using a custom control 
called DigitClass. which we'll examine in 
detail later. Right now, let's look at how 
to place the control using a dialog box 
template. 

The CONTROL statements in the di- 
alog box template specify the DigitClass 
controls. The ones digit of the seconds 
display, for example, is described by the 
line 

CQNTROL " " , IDD_SECDIG, 
"DigitClass", DIGS_LED |. 
WS_CHILD, 95, 5, 3a, 40 

where CONTROL tells Windows to cre- 
ate a control of type DigitClass within the 
dialog box at the x,y coordinates 95, 5 and 
with a size of 30, 40. As with all controls, 
the quantities are specified in dialog units 
based on the size of the Windows system 
font. The label IDD_SECDIG refers to 
the #define statement in TIME.H that 



equates the string IDD__SECDIG to 100, 
the ID tag for this particular control. 

DIGS_LED and WS_CHILD are the 
defined styles for the control. 
DIGS_LED is specific to DigitClass and 
indicates that the digit should initially dis- 
play in red on black. WS_CHILD is a 
standard Windows style for all window 
controls and denotes that the control is 
a child window. 

The window procedure for the parent 
window, WinMain, monitors and com- 
mands all of TIMEl's controls. This in- 
cludes the standard Windows controls 
(such as buttons and sUtie window clas- 
ses) as well as the custom DigjtClass con- 
trols. The procedure is simple, reflecting 
the simple nature of TIME! . While it does 
supervise the various controls, WinMain 
mostly manages the timers. 

The program's timer function uses just 
one Windows system timer for all three, 
of its own. The number of Windows tim- 
ers is limited, so sharing reduces the load 
on the system. To furtlier Ughten de- 
mand, the utility only requests a system 
timer when one of its own runs. 

TIME! calls Windows' SetTimer() 
function to configure a system timer sc 
that it sends a WM_TIMER message 
once a second. Upon receipt of each such 
message, the program calls its Compute- 
Time routine to determine the period 
elapsed since the displayed timer was 
started. The DigitClass controls then 
show the seconds remaining. A call to 
KillTimer releases the Windows timer 
when the utility's last timer expires. 

The rest of TIME! is straightforward. 
The construction of the DigitClass cus- 
tom control and its use are worth looking 
at, so I'll take the time to elaborate on 
those subjects now. 

WINDOWS CUSTOM CONTROLS Before 
implementing a custom control, you 
should ask yourself if you really need it. 
Windows' standard interface is im- 
mensely flexible. It includes numerous 
controls for both collecting user input 
and presenting results. Why should a pro- 
grammer change this interface with a 
nonstandard control? 

The digits in TIME! could have been 
realized either as a custom control or sim- 
ply an embedded window procedure. A 
control is nothing more than a predefineo 
window class packaged in a DLL (dy- 
namic link library). The classic Windows 
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IbiBWiffi'MaeffirPO^System compatibility and superior 
paper handling with a very small footprint and you'll begin to 
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everybody talking. For finer details, contact the Dataproducts 
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As with all good software, the pro- 
grams presented in PC Magazine are 
periodically upgraded and improved. 
Here's a partial list of the programs 
on PC MagNet that have been up- 
dated. To download these files from 
the Utilities/Tips Forum, type GO 
ZNT:TIPS. type LIB or select Librar- 
ies from the menu, then select Library 
2 PCMAG UTILS. Type DOW and 
the filename listed below (for exam- 
ple, DOW ANSLCOM), or select 
Download a File from the menu. 
ADDIT.COM. Version 1.1 
ANSLCOM, Version 1.3 
BAT2EXEC.COM, Version 1.5 
BCOPY, Version 1.2 
CARDFILE.COM, Version 1.1 
CHKFRAG.EXE. Version 1.7 
CONFIG.CTL, Version 3.0 
DIRMATCH.COM, Version 3.1 



push button, for example, could be imple- 
mented by each Windows program as a 
simple window procedu re . 

Controls hold two main advantages 
over embedded window procedures, 
though. The most obviovis is that all pro- 
grams have access to the control rather 
than each requiring its own window pro- 
cedure. A more subtle but equally impor- 
tant advantage is that isolating the win- 
dow class in a control allows you to 
change the control's logic without recom- 
piling the program. 

Your decision about using a custom 
control, then, should be based on port- 
ability across different programs and the 
likelihood of a change in the logic. If you 
plan to employ the control in a number 
of applications or. to facilitate future 
changes, you want to isolate its logic from 
the rest of the program, a custom control 
is the answ er. If, however, you only need 
a special window class for one program, 
then it may not be worth your trouble to 
implement the window as a custom con- 
trol. In the case of the DigitClass control, 
the decision could have gone either way. 
1 do a large amount of Windows pro- 
gramming, though, so I felt that it might 
come in handy later. 

Once you've decided to make a cus- 
tom control, how to design the communi- 



EMMA.COM. Version 2.2 
EMS40.SYS, Version 1.1 
PCACCESS.EXE, Version 1.1 
RN.COM, Version 3.0 
SLICE.COM, Version 1.3 
SNIPPER.COM, Version 1.2 
ZCOPY.COM, Version 1.4 

For a complete list of the programs 
that are available on PC MagNet, 
download PCMCAT.ZIP from Li- 
brary (New Uploads) of the Utilities/ 
Tips Forum. 

A downloadable index to PC Mag- 
azine's product reviews is also avail- 
able in Library 1 (General Info). 
PCM. EXE is a self-extracting file con- 
taming the Computer Library PC 
Magazine Reviews Index for January 
1988 through December 1991. It 
requires the search files in 
PCSRCH.EXE. 

cation mechanism between the program 
and the control wiU be your first problem. 
The control will be isolated from the rest 
of the code, so it can't just share global 
variables! Examining the predefined con- 



trols bundled with Windows reveals the 
solution. Let's look at a standard Win- 
dows check box. 

A window that creates a check box 
control can mark it as checked simply by 
sending it a message. In turn, the check 
box sends a notification message back to 
its parent when it's been clicked. Mes- 
sages are easy and convenient, and they 
provide the simplest form of Windows 
communication. 

The check box is actually a special case 
of the standard Button control. Windows 
defines several messages that let a pro- 
gram govern the look and state of the but- 
ton, including BM_SETSTATE, BM_ 
SETSTYLE, BM_GETSTATE, and 
BM_GETCHECK. At first, it might ap- 
pear as if Microsoft reserved a number 
of messages for the predefined controls 
and none for custom controls. However, 
look at BM_GETCHECK 19 the WIN- 
DOWS. H file suppUed with the Windows 
SDK or Borland's C++ 3.0 compiler and 
you'll see how Microsoft designed the 
control messages so that custom controls 
can use them too. 

BM_GETCHECK is defined as 
WM_USER+0. Starting at the messag 
number WM_USER, Windows reserves 
a large number of Windows messages for 



' Using the DigitClass Control 



Custom controls can be conveniently 
reused when you program new Win- 
dows apps, and this makes them pow- 
erful tools. Both the Dialog Box edi- 
tor in the Microsoft Windows SDK 
and the Resource Workshop bimdled 
with Borland's C++ 3. 1 compiler allow 
custom controls to be used as if they 
were part of the standard Windows 
controls. Let's look at how to use the 
DigitClass control with the SDK. 

Start the SDK's dialog editor and 
select File Open Custom Control from 
the menu. A dialog box will appear 
and you can enter the path to 
D1G1T.DLL and the DigitClass con- 
trol will automatically be loaded. 

To put the control in a dialog box, 
select the custom icon in the conlxol 
toolbox. The pointer will change to a 
box as you move it back over the out- 



mouse inside the new dialog box ta" 

place the control. If you have more 
than one custom control installed in 
it, the editor will ask which you want 
when you press the custom icon. 

Using custom controls with Bor- 
land's Resource Workshop is just as 
simple. Select Options Install Custom 
Control Library from the menu to in 
stall the control and choose Controls 
Custom to place it. Then add the 
DIGIT.H file to the list of #include 
files used by the project by selecting 
the Add to Project menu. Since the 
Resource Workshop comes with a 
number of custom controls, you will 
always be asked which you wish to use. 

Once installed, it's as simple to use 
a custom control as any of the stan- 
dard controls. With custom controls, 
though, your program takes on a loi 
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Microsoft does it right by bringing 
together full-featured Windows versions 
of Word, Excel, PowerPoint and Mail in 
one convenient package. And Software 
Spectrum does it right too by bringing 
Microsoft Office for Windows to you at a 
great price — only $459. What's more, 
we've got low prices on other products 
from Microsoft. Plus the best service in 
the industry. And that does it. Right! 
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Figure 1: This f^ra shows the TIME! window with the fbur 
DigitClasscustoin controls. 



window procedures to use as they see fit. 
One twist seems to foul the works, 
though: The standard controls also em- 
ploy this range of WM_USER message 
numbers for corcmand messages. 
EM_GETSEL, used by the edit control, 
for instance, is also defined as 
WM_USER+0. 

Since a number of controls use the 
same message nimiber for different com- 
mands, what prevents chaos? In the case 
of the example above, since you send the 
BM_GETCHECK message to a check 
box and EM_GETSEL to an edit control, 
each control remains unaffected by the 
other's use of the same message number. 

Just as messages command a control, 
they also are issued when a control must 
notify its parent window of an event. In 
this case, though, the neat trick of using 
mmibers that are o^ets from the 
WM_USER message won't wofk. Not 
only could different controls send notifi- 
cation messages with different meanings 
to the same parent, the parent window 
might employ the WM_USER range of 
message numbers for its own purposes. 
As with the control messages, the solu- 
tion can be found in the design of the pre- 
defined controls. 

When clicked, the check box control 
notifies its parent by sending a 
WM_COMMAND message containing 
IParam, which holds the notification code 
in its upper word and the handle of the 
check box window in its lower word. The 
ID number of the control, set when the 
control was created, is found in wParam. 
Using unique IDs for each of its child 
window controls, the parent determines 
precisely which one sent the message and 



with that, figures out the mean- 
ing of the notification code in 
IParam. The WM_COM- 
MAND notification system is 
used by all of Windows' stand- 
ard controls. 

THE DIGITCLASS CONTROL 
DigitClass — a rather simple 
control — displays a number be- 
tween and 15, representing 
those above 9 in hexadecimal 
fashion, where the letter A cor- 
responds to 10, B to 11, and so 
on. (Actually, TIME! never 
shows hex numbers, but includ- 
ing this abiUty gives DigitClass 
" more flexibility for future ap- 
pHcations.) The control accepts no num- 
ber greater than 15 and a program can 
instruct it to further restrict the permissi- 
ble range (to numbers between and 5, 
for example). 

You can view the choice of this upper 
limit as equivalent to determining the 
control's numerical base. Configuring the 
DigitClass control to accept nothing 
above 9, for example, is the same as mak- 
ing its base 10. (In base arithmetic, only 
numbers below the base are valid.) 

Using GDI (Graphics Device Inter- 
face) commands, DigitClass draws lines 
to simulate the seven segments of LCD 



and LED displays. Depending on the 
control's style setting, a decimal poin 
and a colon can be presented in addition 
to the number, and the colors can be set 
to either the LCD or LED mode. 

The control also remembers the dis- 
played numeral; once set, the DigitClass 
control will continue to show it until in- 
structed by another command to change 
the display. 

The number displayed by a DigitClass 
control can be incremented or decre- 
mented simply by sending a message. 
Normally, when the control receives an 
increment command, it advances the 
stored number and displays it. If a mmi- 
ber grows larger than the preset upper 
limit (its base), then it sets itself to and 
sends a carry message. If the number dec- 
rements below 0, then it sets itself to the 
largest valid digit and sends a borrow 
message. The display is then set to 0. 

Finally, the number stored, the style, 
and the current base setting can also be 
queried using various messages, as we'll 
see shortly. 

GET THE MESSAGE? The DigitClass 
control uses the WM_USER message 
range for passing command messages, a 
do standard window controls. Seven mes- 
sages (WM_USER^-l to WM_USER-i-7) 
are defined for the control: DIGM_SET, 



MAIN WINDOW DIALOG BOX 

Complete Listing 



Main window Dialog box 



WinTiitie DIALOG LOADONCALL MOVEABLK DISCARDABLE 100, 122, 130, 120 

STYLE WS_BORDER ] WS_CaU«rICai I WS_DLGFHAHE | WS_SYSMEND | WS_MINIMIZEBOX 



CLASS " Time ! " 

CAPTION "Time!' 

FONT 8, "MS Sans Serif 

MENU WinTime 

BEGIN 



CONTROL 




"", IDD 


_TMINDIG, 


"DigitClass" , 














DIGS_LED j 


WS_CHILD, 


5, 


5, 


38, 


40 


COOTROL 




" " , IDD 


_MINDIG, 


"DigitClass" , 














DIGS_LED 


WS_CHILD, 


35, 


5, 


30, 


40 


COSTROL 




" " , IDD 


^TSECDIG, 


"DigitClass" , 










WS_ 


CHILD DIGS 


_COLON 1 


DIGS_LED, 


S5, 


5, 


30, 


40 


CONTROL 




■ ■ , IDD 


_SECDIG, 


"DigitClass" , 














DIGS_LED i 


WS__CHILD, 


95, 


5, 


30, 


40 


CONTROL ■■ 


IDD, 


_MTIME1, 


"Static" , 


SS_BLACKRECT, 


5. 


48, 


36, 


2 


CONTROL ■■ 


IDD. 


_MTIME2 , 


"static" 


SS_BLACKRECT, 


47, 


48, 


37, 


2 


CONTROL " " 


IDD 


_MTIME3, 


"static " 


SS_BLACKRECT, 


89, 


48. 


36, 


2 


PUSHBUTTON 




"Timer 


S.1' . 


IDD_BTIMER1 , 


5, 


52, 


36, 


15 


PUSHBUTTON 




" Timer 


£.2" , 


IDD_BTIMER2 , 


47, 


52, 


37, 


15 


PUSHBUTTON 




"Timer 


S3" , 


IDD_BTIMER3 , 


89, 


52, 


36, 


15 


«JSHBUTTON 




" &Minutes " , 


IDD_BMINUTES, 


5, 


72, 


57, 


20 






" fiSeconds " , 


IpE_BSBGONDS , 


68, 


72, 


57, 


20 


PUSHBUTTON 




"SStart 




IDD_GO, 


5, 


97, 


120, 


20 



figure 2: This Is the listing of the dialog-box template for the main window of Time!. The four statements 
starting with the word CONTROL are the lines that specify the instances of the DigitClass control. 
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''alpha four is indispensadle! 
i can develop powrful 
relational database 
applications even thouoh tm a 

non-programmer;' 

— Bruce Berenson, Vice-President; Belgacom, USA 

Bruce Berenson, Vice-President of Belgacom, USA, 
uses a custom-designed Alpha Four database 
everyday. He tried dBASE® (too complicated) 
and Q&A® (not powerful enough). But with 
Alpha Four, Bmce easily designed a professional 
application to suit his needs. It's the one fully- 
relational database that empowered him to create 
a completely customized application — without 
programming! Now Bruce, and his co-workers, 
are among the over 400,000 satisfied 
Alpha Four customers worldwide. 

Alpha Four is the only relational 
database specifically designed for 
non-programmers who need 
serious database solutions. 

Alpha Four's menu-driven interface is so 
intuitive, you almost forget that you're 
working with a powerful, relational 
database. With lightning fast indexes, 
professional quality applications, dialog 
boxes, conditional logic mail merge, 
mail labels and powerful report writing. 
Alpha Four fulfills all your database needs. 
And, Alpha Four uses the standard dBASE 
file format so you never have to worry 
about compatibility. 

PC Week gave Alpha Four a #1 Rating and 
PC Magazine (Feb. 25, 1992) states, "Alpha Four 
Version 2 delivers on the promise to be even 
more powerful without giving up any of the 
features that earned it our Editor's Choice." 

For information, a FREE demo disk, or to order, 

call 1-800-852-5750, ext m. 

Alpha Software Corporation 
^ l=^'f^ 168 Middlesex Tumpil<e 
= «= «= Burlington, MA 01803 USA 

617-229-2924; fax: 617-272-4876 
Available through dealers worldwide. 

QFS 




According to IDC. Alpha Four iS the fastest growing, 
best-selling relational database 'for non-programmers. 
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DIGM_GET, DIGM_INC, DIGM_ 
DEC, DIGM_SETB ASE, DIGM^GET- 
BASE, and DIGM_BLANK. Since pro- 
grams that use the DigitClass control 
need to know which message number 
goes with which command, the numbers 
are assigned in the separate file 
DIGIT.H, which is listed in Figure 3. 

DIGM_SET sets the number that the 
control will display. The number is 
passed in the message's wParam (IParam 
is not used). The number can be between 
and 15 as long as it does not exceed 
the base of the control. If a program at- 
tempts to set a number above the base, 
the DigitClass control sets the number to 
one less than the Base. 

The DIGM_SETBASE message sets 
the numeric base, with the base passed 
in wParam. Like DIGM_SET, the 
DIGM_SETBASE message does not use 
iParam. Since 15 is the highest number 
allowed, 16 is the maximum base value. 
If a program attempts to set it higher, the 
control forces it to 16. The miliimum pos- 
sible base is 2. 

DIGM_INC advances the displayed 
number and DIGM_DEC decrements it. 
These messages use neither wParam nor 
IParam. 

DIGM„BLANK instructs TIME! to 
blank the display. DIGM_GET and 
DIGM_GETBASE let the parent win- 
dow query the control about the number 
displayed and the base, respectively. 
These three messages use neither 
wParam nor IParam. 

No messages exist that govern the dis- 
play of the decimal and colon but they, 



Utilities 

as well as colors, can be managed by set- 
ting the style bits for the control. The 
Windows API function calls, GetWin- 
dowLong and SetWindowLong, accom- 
plish the task. 

The DigitClass control uses the same 
WM_COMMAND notification scheme 
as the standard controls, employing one 
of four notification codes: DIGN_ 
CARRY, DIGN_BORROW, DIGN_ 
LCLICK, and DIGN_RCLICK. As with 
the standard Windows controls, the 
codes are sent in the high word of IParam 
(in a WM_COMMAND message). The 
low word of IParam holds the control 
window handle and wParam carries the 
control ID. 

The notification codes themselves are 
fairly self explanatory. DIGN_CARRY 
is sent when the DigitClass control is in- 
cremented past its base. If, for example, 
the base has been set to 6 and a 
DIGM_INC message is forwarded to the 
control (currently displaying a 5), the 
control will display a and post a 
DIGN_CARRY notification to its par- 
ent. DIGN_BORROW is posted if the 
control is decremented below 0. In this 
case, DigitClass will display one less than 
the base and then send the 
DIGN_BORROW notification. 

Clicking on the DigitClass control 
sends DIGN_LCLICK if caused by the 
left mouse button or DIGN_RCLICK if 
caused by the right. More specifically, the 
notification is sent when a DigitClass 
window receives a WM_LBUTTONUP 
or WM_RBUTTONUP message. 

CONSTRUCTING A CONTROL DigitClass 



is implemented in a DLL (DIGIT.DLL), 
as are all Windows controls. Bundhng thf 
code in a DLL, however, isn't the only, 
overhead incurred when writing a con- 
trol; a number of required routines must 
be added to integrate it into the various 
dialog-box editors that developers use. In 
the case of the DigitClass control, this in- 
volves as much work as writing its win- 
dow procedure! 

As with any DLL, DIGIT.DLL eon- 
tains a LibMain procedure called when 
the DLL first loads into memory. The 
procedure is comparable to the WinMain 
function called when a Windows pro- 
gram executes. In DigitClass, LibMain 
registers the DigitClass window class. 
This allows programs to create Digit- 
Class controls by simply loading 
DIGIT.DLL and calhng one of the win- 
dow-creation functions (such as 
Create Window). 

The next series of dynamic link 
library procedures are specific to custom- 
control DLLs and follow the naming 
scheme recommended by Microsoft. The 
names of the routines — DigitWndFn, 
Digitlnfo, DigitStyle, DigitDlgFn, and 
DigitFlags — are customized for th 
DigitClass control. Following this guide-- 
line, procedure names for a custom con- 
trol called Wigit, for example, would be 
WigitWndFn, Wigitlnfo, WigitStyle, and 
so forth. 

The routines are referenced by their 
ordinal numbers. The ordinal number for 
a procedure is its position in the hst of 
callable routines in the DLL header. 

DigitWndFn is the window procedure 



DIGIT.H 

Complete Listing 



//__ 

// DroiT.H — Include file for DIGIT. DLL and the DigitClass GoHtrbl 
// 

// (c) Douglas Boling, 1992 

// , . 

// 

■// Digit Control Styles 
>/ 

#Be£ins DIGS^LED 0XB881L 
tdeline DIGS_BLANK 0X0002L 
itdefine DIGS_COLON 0X0004L 
#define DIGS_DECIMAL 0X00081 
// 

// Digit Contol Style labels (These strings must match above defines.) 

// 

tdefine DIGS_LEDSTR ■DIGS_LED" 
tdefine DIGS_BLiSNKSTH ■DIGSJLAMK" 
#dbfine DIGS_COLOKSTR "DIGS_COLON" 
#dGfine DIGS„DECIMM,STR "DIGSJECIMAL" 
// 

// Digit Control Messages 
// 

tdaiins DJGM1.SET (WK_HSER+1) ' 



(WM_USER+3 ) 
(WM_USER+4 ) 
(WM_USER+5} 
(WM_USER+6) 
(WMJSEK-tV) 



#define DIGM_INC 
#define DIGM_DEC 
#define DIGM_SETBASE 
#define DIGM_GET.BASE 
#define DIGM_BLAIJK 
// 

// Digit Notification Messages 
// 

#define DIGN„CARRY 1 
tdefine DIGN_BORROW 2 
ftdefine DIGN_LCLICK 3 
#define DIGN_RCL1CK 4 
// 

// IDs for Style and About dialog boxes used with the dialog box editors. 

// 

itdefine IDD_^ABOUT 200 

#define IDD_BLANK 101 

#define IDD_COLON 102 

#define IDD_DECIMAL 103 

#dGfine IDD_LED 104 ^^^^ 

#define IDD„LCD 105 1^^^^ 

#define IDD_CTLID 106 I U M 
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DIGIT.DEF 

Complete Listing 



DIGIT.DEF module definition file 
Copyright (c> Douglas Boling 1992 



LIBRARY 

DESCRIPTION 
EXETYPE 
CODE ' ■ ! i 

DATA 



DIGIT 

•Digit Control, Copyright 1992, Douglas Boiing" 

WINDOWS 

PRELOAD MOVEABLE ■ ' ' ■ 

PRELOAD MOVEABLE 

8192 



LIBMAIN 
WEP 

DIGITINFO 
DIGI^TSTYLS 



^KFB 4: This is a link definition file that assigns the erdlnal numbers for the OlgitClass procedures. 



for the DigitClass window and is identical 
to what would have been written had the 
control been implemented as a window 
class inside the jwi^sffl., IM^tWndFn 
handles window messages sent to the 
window, such as WM_CREATE, 
WM_PAINT. and WM_COMMAND. It 
also must manage WM_USER messages 
that have been equated with control com- 
mands. In the case of DigitClass, it deals 
ith DIGM_SET and the other com- 
mand messages relayed to the control. 

DigitWndFn also sencfe the WM_ 
COMMAND messages containing the 
notification codes. These messages are 
sent to the parent of the DigitClass win- 
dow, as id^tennined by a cidi to the ttet- 
pM'ent Windows API function. Notifica- 
tion messages are sent out in response to 
the conditions mentioned above. For ex- 
ample, when Digit WndFo rjeceiyes a 
WM_LBUTTONUP message, it sends 
the notification D1GN_LCLICK to the 
control's parent window. 

A series of GDI MoveTo and LineTo 
calls displays the LED segments in re- 
sponse to the WM_PAINT message. The 
DigitClass window's dimensions deter- 
mine the position and width of the lines. 

Dialog-box editors use the remaining 
DIG1T.DLL procedures. Both the 
SDK's editor (DLGEDIT.EXE) and the 
Resource Workshop bundled with the 
Borland C++ 3.0 compiler (WORK- 
SHOP.EXE) can load custom controls 
that use the custom control interface em- 
^loyed by DigitClass. The routines in the 
justom control pLL allow these editors 
to use ani#A^% flie contfol&isiiftOnt 
knowing, th^ jwfifk pr even what 



they look like! To learn how to load and 
use the DigitClass control in DLGEDIT 
and WORKSHOP, read the sidebar "Us- 
ing the DigitClass Control." 

The Digitlnfo procedure allows a dia- 
log-box editor to query the control for in- 
formation, such as the copyright, the ver- 
sion number, the control's name, and its 
default size and style. The procedul^i^v'J 
self is simple. It allocates global memory 
for the information structure, fills in the 
structure, and then passes the handle 
back to the editor (pl^di past 
the memory block after reading the infor- 
mation). 

The dialog-box editor calls DigitStyle 
to instruct the eiisftoi&-ti6itf'e>l DLL' to 

display the control's Style dialog box. 
Most dialog-box editors call this routine 
when the user double-clicks on the con- 
trol. Suppose a user double-clicks on a 
DigitClass control (to set its styles) just 
placed on the dialog box being created. 
In DigitClass, the DigitStyle routine gen- 
erates a procedure instance for the Style 
dialog-box procedure, displays the box 
using Windows' DialogBox function, 
then frees the instance (with FreeProc- 
Instance) once the function returns. 

When DigitStyle is called, a word con- 
tains a handle to a block of memory that 
contains the control's current style struc- 
ture. The style double-word (DWORD) 
in this structure contains the current style 
settings. The dialog box is charged with 
the job of querying the user aboout any 
style changes and passing the new control 
style back to the editor in the style 

The window proce^wre for style 



dialog box (DigitDlgFn) is a standard di- 
alog-box procedure that responds to no- 
tification messages from the dialog-box 
controls. The dialog-box controls are de- 
fined in the Style dialog-box template 
bound with the DigitClass DLL. When 
the user presses the OK button on the 
Style dialog, its procedure updates the 
control's Style DWORD and destroys 
the dialog box with a call to EndDialog. 
Conversely, if the user presses the Cancel 
button, the Style DWORD is passed back 
to the dialog-box editor unmodified. 

The DigitFlags procedure translates 
the state of the style bits into the labels 
used in DIGIT.H. The labels arc then 
written into the resulting .DLG file for 
the dialog box. When called, the routine 
is passed three parameters: the Style 
DWORD, a pointer to an ASCIIZ string, 
and the maximum length of that string. 
DigitFlags must examine the Style 
DWORD and append the appropriate 
style tags to the ASCIIZ string. For ex- 
ample, if the Style DWORD has the LED 
display bit set, DigitFlags would append 
the DIGS_LED string to the ASCIIZ 
string. The dialog-box editor would then 
use the resulting string in the .DLG file's 
CONTROL statement that specifies the 
control. 

The procedures we've discussed pro- 
vide everything a dialog-box editorneeds 
to create a CONTROL stat&ttlent in the 
dMog template. The editor can deter- 
mine the name of the control class by call- 
ing the Digitlnfo procedure. The dialog 
editor can display a custom style dialog 
box for the conbrol by calling DigitStyle. 
When the user moves the control, its po- 
sition and size are determined by the dia- 
log-box editor. Finally, the editor calls 
the DigitFlags routine to convert the 
style bits into the labels used in the .DLG 
file. This combination of routines allows 
the dialog-box editor to produce the 
.RES and .DLG files, j, . 

DigitClass furnishes a simple exam- 
ple, but it demonstrates all the necessary 
routines for a custom control. It also 
demonstrates all the necessary routines 
for a custom control. And. it demon- 
strates that the ideas behind the standard 
controls can be applied to controls cus- 
tomized for specific applicatiom- □ 
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DIGIT.DEF 

Complete Listing 



DIGIT.DEF module definition file 
Copyrxglit (c) fiouglas Bolang 



DESCRIPTION 

EXETYPE 

CODE 

DATA 

HEAPSIZE 



DIGIT 

'Digit Control, Copyright 1992, Douglas Boling' 
WINDOWS 

PRELOAD MOy^I^ ■ ,-, , , ; / _ ' 

PRELOAD MOVEABLE 

8192 



LIBMAIN 
WEP 

DIGITINFO 
DIGITSTYLE 




Figure 4: This Is a link definition file that assigns tlie ordinal numbers for the DigitClass procedures. 



for the DigitClass window and is identical 
to what would have been written had the 

control been implemented as a window 
class inside the program. DigitWndFn 
handles window rriessiages sent to the 
window, such as WM_CREATE, 
WM_PAINT, and WM_COMMAND. It 
also must manage WM_USER messages 
that have been equated with control com- 
mands. In the case of DigitClass, it deals 
dth DIGM_SET and the other com- 
mand message^ relayed jtQ the coBtrol. , 

DigifWiilFn' 'Ststy 'tfe-lWTViL' ' 

COMMAND messages containing the 
notification codes. These messages are 
sent to the parent of the DigitClass win- 
dow, as determined by a call to the Get- 
Parent Windows API function. Notifica- 
tion messages are sent out in response to 
the conditions mentioned above. For ex- 
ample, when DigitWndFn receives a 
WM_LBUTTONUP message, it sends 
the notification DIGN_LCLICK to the 
control's parent window. 

A series of GDI MoveTo and LineTo 
calls displays the LED segments in re- 
sponse to the WM_PAINT message. The 
DigitClass window's dimensions deter- 
mine the position and width of the lines. 

Dialog-box editors use the remaihing 
DIGIT.DLL procedures. Both the 
SDK's editor (DLGED1T.EXE) and the 
Resource Workshop bundled with the 
Borland C++ 3.0 compiler (WORK- 
SHOP .EXE) can load custom controls 
that use the custom control interface em- 
oloyed by DigitClass. The routines in the 
justom control DLL allow these editors 
to use and display the controls without 
knowing how they work or even what 



they look like! To learn how to load and 
use the DigitClass control in DLGEDIT 
and WORKSHOP, read the sidebar "Us- 
ing the DigitClass Control." ^ 

The'-Digitlnfb proceciure allows a dia- 
log-box editor to query the control for in- 
formation, such as the copyright, the ver- 
sion number, the conirol's name, and its 
default size and style. The procedure it- 
self is simple. It allocates global memory 
for the information structure, fills in the 
Structure, ^d then passes the handle 
' bafek id the editor (which must release 
the memory block after reading the infor- 
mation). 

The dialog-box editor calls DigitStyle 
to instruct the custom-control DLL to 
display the control's Style dialog box. 
Most dialog-box editors call this routine 
when the user double-clicks on the con- 
trol. Suppose a user double-clicks on a 
DigitClass control (to set its styles) just 
placed on the dialog box being created. 
In DigitClass, the DigitStyle routine gen- 
erates a procedtire instance for the Style 
dialog-box procedure, displays the box 
using Windows' DialogBox ftmction, 
then frees the instance (with FreeProc- 
Instance) once the function returns. 

When DigitStyle is called, a word con- 
tains a handle to a block of memory that 
contains the control's current style struc- 
ture. The style double-word (DWORD) 
in this structure contains the currejjtjtyte 
settings. The dialog box is charged with 
the job of querying the user aboout any 
style changes and passing the new control 
style back to the editor in the style 
DWORD. 

The window procedure for the style 



dialog box (DigitDlgFn) is a standard di- 
alog-box procedure that responds to no- 
tification messages from the dialog-box 
controls. The dialog-box controls are de- 
fined in the Style dialog-box template 
bound with the DigitClass DLL. When 
the user presses the OK button on the 
Style dialog, its proeedi^e. updates the 
control's Style DWORD and destroys 
the dialog box with a call to EndDialog. 
Conversely, if the user presses the Cancel 
button, the Style DWORD is passed back 
to the dialog-box editor unmodified. 

The DigitFlags procedure translates 
the state of the style bits into the labels 
used in DIGIT.H. The labels are then 
written into the resulting .DLG file for 
the dialog box. When called, the routine 
is passed three parameters: the Style 
DWORD, a pointer to an ASCIIZ string, 
and the maximum length of that string. 
.^DimtFlags^ must exanaine the Style 
i)W(5RD and append the appropriate 
style tags to the ASCIIZ string. For ex- 
ample, if the Style DWORD has the LED 
display bit set, DigitFlags would append 
the DIGS_LED stjii^ to the, ASCIIZ 
string. The dialog-box editor would then 
use the resulting string in the .DLG file's 
CONTROL statement that specifies the 
DigitClass control. ' ' ^ 

The procedures we've discussed pro- 
vide everything a dialog-box editor needs 
to create a CONTROL statement in the 
dialog template. The editor can deter- 
mine the name of the control class by call- 
ing the Digitlnfo procedure. The dialog 
editor can display a custom style dialog 
box for the control by calling DigitStyle. 
When the user moves the control, its po- 
sition and size are determined by the dia- 
log-box editor. Finally, the editor calls 
the DigitFlags routine to convert the 
style bits into the labels used in the .DLG 
file. This combination of routines allows 
the dialog-box editor to produce the 
.RES and .DLG files. 

DigitClass furnishes a simple exam- 
ple, but it demonstrates all the necessary 
routines for a custom control. It also 
demonstrates all the necessary routines 
for a custom control. And, it demon- 
strates that the ideas behind the standard 
controls can be applied to controls cus- 
tomized for specific apphcations. □ 
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